<HTML><HEAD><TITLE>cursor_N_execute(++Cursor, -Executed, +TupleList, -RestTupleList)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(dbi)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>cursor_N_execute(++Cursor, -Executed, +TupleList, -RestTupleList)</H1>
Executes the parametrised prepared SQL statement represented by Cursor, once for each tuple in TupleList.
<DL>
<DT><EM>Cursor</EM></DT>
<DD>A cursor handle
</DD>
<DT><EM>Executed</EM></DT>
<DD>Number of times the SQL statement was executed.
</DD>
<DT><EM>TupleList</EM></DT>
<DD>A difference list (together with RestTupleList) of tuples of parameter values matching the template for this cursor
</DD>
<DT><EM>RestTupleList</EM></DT>
<DD>Tail of tuple difference list
</DD>
</DL>
<H2>Description</H2>
<P>
 Executes the parameterised prepared SQL statement represented by Cursor,
 previously prepared by session_sql_prepare/4 or session_sql_prepare_query/5.
 The predicate executes a number of tuples from TupleList, taking the
 tuples in order from the start of the list, leaving the unprocessed tuples
 in RestTupleList. The number of tuple processed is unified with Executed.
 Any results produced when executing a tuple is discarded when the next
 tuple is processed.
</P><P>
 The number of tuples processed per call is determined by the library. 
 This freedom allows the  predicate to process a multiple number of tuples
 in the most efficient way for the DBMS.
</P><P>
 Each tuple is a structure whose name and arity match the parameter
 template when Cursor was prepared, and the arguments give the values for
 the parameters for this execution, and must be compatible with the type
 specified by the template, except that an argument can be an
 uninstantiated variable, to denote a NULL value for the corresponding
 parameter.
</P><P>
 MySQL specific note: MySQL does not support the execution of multiple
 tuples in one go, so for MySQL, this predicate is essentially equivalent
 to executing cursor_next_execute/1 multiple times.

<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>Cursor is not a valid cursor handle
<DT><EM>(5) type error </EM>
<DD>Type mismatch between parameter template specification for Cursor and actual tuple data
<DT><EM>(dbi_error) </EM>
<DD>Error from DBMS while executing SQL associated with Cursor.
<DT><EM>(dbi_bad_template) </EM>
<DD>ParamTemplate not specified when Cursor was created
</DL>
<H2>Examples</H2>
<PRE>
  transfer_(Session, Amount, FromAccount, ToAccount) :-
      SQL = "update accounts set balance = balance + ?                                                where id = ?",
      Deduct is - Amount,
      session_sql_prepare(Session,incbal(1.0,12),SQL,2,Update),
      Updates = [incbal(Deduct,FromAccount),incbal(Amount,ToAccount)],
      % execute both updates with one call to cursor_N_execute/4
      cursor_N_execute(Update,2,Updates,[]).
</PRE>
<H2>See Also</H2>
<A HREF="../../lib/dbi/cursor_next_execute-2.html">cursor_next_execute / 2</A>, <A HREF="../../lib/dbi/cursor_N_execute-4.html">cursor_N_execute / 4</A>, <A HREF="../../lib/dbi/session_sql_prepare-4.html">session_sql_prepare / 4</A>, <A HREF="../../lib/dbi/session_sql_prepare_query-5.html">session_sql_prepare_query / 5</A>
</BODY></HTML>
